onetime

What is onetime?

The 'onetime' npm package is designed to ensure a function can only be called once. It is useful for initialization routines, event handlers, or any other situation where a function should only execute a single time and subsequent calls should either return the result of the first call or throw an error.

What are onetime's main functionalities?

Ensuring a function is only called once

This feature allows you to wrap a function with 'onetime' to ensure it can only be executed once. Subsequent calls to the function will have no effect.

const onetime = require('onetime');

const initialize = onetime(() => {
  console.log('Initialization complete.');
});

initialize(); // 'Initialization complete.'
initialize(); // No output, function not called again

Throwing an error on subsequent calls

This feature allows you to configure 'onetime' to throw an error if the function is attempted to be called more than once, which can be useful for debugging.

const onetime = require('onetime');

const doOnce = onetime(() => {
  console.log('Done once.');
}, {throw: true});

doOnce(); // 'Done once.'
try {
  doOnce(); // Throws an Error because the function was already called.
} catch (e) {
  console.error(e.message); // 'Function can only be called once.'
}

Checking if a function has been called

This feature provides a way to check if the onetime-wrapped function has been called, which can be useful for conditional logic based on whether the initialization or setup has already been performed.

const onetime = require('onetime');

const onceFn = onetime(() => {});

console.log(onetime.called(onceFn)); // false
onceFn();
console.log(onetime.called(onceFn)); // true

Other packages similar to onetime

once

The 'once' package is similar to 'onetime' in that it ensures a function can only be called once. The main difference is in the API and additional features that 'once' might provide, such as the ability to clear the once wrapper and allow the function to be called again.

lodash.once

Provided by the popular Lodash library, 'lodash.once' is a function that ensures a given function can only be called once. It is similar to 'onetime' but comes as part of the larger Lodash utility library, which might be preferable if you are already using Lodash in your project.

README

onetime

Ensure a function is only called once

When called multiple times it will return the return value from the first call.

Unlike the module once, this one isn't naughty and extending Function.prototype.

Install

$ npm install onetime

Usage

const onetime = require('onetime');

let i = 0;

const foo = onetime(() => ++i);

foo(); //=> 1
foo(); //=> 1
foo(); //=> 1

onetime.callCount(foo); //=> 3

const onetime = require('onetime');

const foo = onetime(() => {}, {throw: true});

foo();

foo();
//=> Error: Function `foo` can only be called once

API

onetime(fn, options?)

Returns a function that only calls fn once.

fn

Type: Function

Function that should only be called once.

options

Type: object

throw

Type: boolean
Default: false

Throw an error when called more than once.

onetime.callCount(fn)

Returns a number representing how many times fn has been called.

Note: It throws an error if you pass in a function that is not wrapped by onetime.

const onetime = require('onetime');

const foo = onetime(() => {});

foo();
foo();
foo();

console.log(onetime.callCount(foo));
//=> 3

fn

Type: Function

Function to get call count from.

onetime for enterprise

Available as part of the Tidelift Subscription.

The maintainers of onetime and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.